The HealthQuantitySample class represents a single health quantity data point, such as a heart rate measurement, a recorded step count, or a logged calorie value. It provides information about the measurement’s type, time interval, unit, value, and optional metadata.

This class is the base for more specialized subclasses: HealthCumulativeQuantitySample and HealthDiscreteQuantitySample.

Overview#

A HealthQuantitySample encapsulates the following:

• A specific health metric (e.g., steps, heart rate)
• A value with unit
• A time window representing when the data was recorded
• Optional metadata for context or classification

This class is primarily used for:

• Reading individual health data samples
• Writing new health data samples
• Converting values between units

Properties#

Methods#

quantityValue(unit: HealthUnit): number#

Converts the sample's stored value to the specified unit.

Parameters:

• unit: A HealthUnit instance (e.g., HealthUnit.kilocalorie())

Returns:

• The converted numeric value.

Example:

1const bpm = sample.quantityValue(HealthUnit.count().divided(HealthUnit.minute()))
2console.log(`Heart Rate: ${bpm} bpm`)

Static Methods#

HealthQuantitySample.create(options): HealthQuantitySample | null#

Creates a new quantity sample with the specified parameters.

Parameters:

1{
2  type: HealthQuantityType
3  startDate: Date
4  endDate: Date
5  value: number
6  unit: HealthUnit
7  metadata?: Record<string, any> | null
8}

Returns:

• A new HealthQuantitySample if valid, otherwise null.

Example:

1const sample = HealthQuantitySample.create({
2  type: 'stepCount',
3  startDate: new Date('2025-07-01T09:00:00'),
4  endDate: new Date('2025-07-01T09:01:00'),
5  value: 200,
6  unit: HealthUnit.count(),
7  metadata: { source: 'manualEntry' }
8})

Subclass: HealthCumulativeQuantitySample#

The HealthCumulativeQuantitySample class represents cumulative data (i.e., totals over time), such as energy burned or distance traveled.

Additional Properties#

Additional Methods#

sumQuantity(unit: HealthUnit): number#

Returns the total accumulated quantity in the specified unit.

Example:

1const totalKcal = cumulativeSample.sumQuantity(HealthUnit.kilocalorie())
2console.log(`Total active energy: ${totalKcal} kcal`)

quantityValue(unit: HealthUnit): number#

Alias for sumQuantity() — retrieves the total value in the given unit.

Subclass: HealthDiscreteQuantitySample#

The HealthDiscreteQuantitySample class represents a series of discrete values sampled at specific times — such as heart rate measurements or step counts across a time window.

Additional Properties#

Additional Methods#

Example:#

1const avg = discreteSample.averageQuantity(HealthUnit.count())
2const max = discreteSample.maximumQuantity(HealthUnit.count())
3const recent = discreteSample.mostRecentQuantity(HealthUnit.count())
4console.log(`Average: ${avg}, Max: ${max}, Recent: ${recent}`)

Use Cases#

Related Types#

• HealthUnit: Represents the unit of measurement.
• HealthQuantityType: Specifies the kind of health metric being measured.
• HealthDateInterval: A time range used for timestamping specific values.